PostgreSQL 17에서 18로 업그레이드 가이드: 주요 이슈 및 해결법

PostgreSQL의 메이저 버전 업데이트는 항상 설레는 일이지만, 데이터 마이그레이션 과정에서 예상치 못한 오류를 마주하기도 합니다. 이번 포스트에서는 PostgreSQL 17에서 18로 업그레이드할 때의 표준 절차와 제가 직접 겪었던 트러블슈팅 사례를 공유합니다.

1. 업그레이드 전 준비사항

메이저 업데이트 전에는 반드시 기존 데이터를 백업해야 합니다.

• 데이터 백업: pg_dumpall을 사용하여 전체 클러스터를 백업합니다.
• 확장 기능(Extensions) 확인: PostGIS, TimescaleDB 등 사용 중인 익스텐션이 PostgreSQL 18을 지원하는지 확인합니다.
• 용량 확인: pg_upgrade의 --link 모드를 사용하지 않는다면, 데이터 디렉토리 크기의 약 2배 정도의 여유 공간이 필요합니다.

2. 표준 업그레이드 절차 (pg_upgrade)

일반적으로 가장 권장되는 방식은 pg_upgrade 도구를 사용하는 것입니다.

# 1. 이전 버전과 새 버전의 바이너리 설치 확인
# 2. 새 버전의 데이터 디렉토리 초기화 (initdb)
# 3. 업그레이드 체크 (문제가 없는지 먼저 확인)
pg_upgrade \
  --old-datadir /var/lib/postgresql/17/main \
  --new-datadir /var/lib/postgresql/18/main \
  --old-bindir /usr/lib/postgresql/17/bin \
  --new-bindir /usr/lib/postgresql/18/bin \
  --check
 
# 4. 실제 업그레이드 실행 (--link 옵션은 하드링크를 사용하여 속도가 매우 빠름)
pg_upgrade \
  --old-datadir /var/lib/postgresql/17/main \
  --new-datadir /var/lib/postgresql/18/main \
  --old-bindir /usr/lib/postgresql/17/bin \
  --new-bindir /usr/lib/postgresql/18/bin \
  --link

3. 마주했던 주요 문제와 해결법

업그레이드 과정에서 제가 겪었던 주요 이슈들은 다음과 같습니다.

이슈 1: ICU 로케일 불일치 오류

PostgreSQL 17부터 ICU 로케일 지원이 강화되었는데, 18로 넘어오면서 시스템의 ICU 라이브러리 버전이 업데이트되어 pg_upgrade 중 인덱스 정렬(Collation) 충돌이 발생할 수 있습니다.

해결 방법:

• 업그레이드 후 REINDEX DATABASE 또는 REINDEX INDEX를 실행하여 인덱스를 다시 빌드해야 합니다.
• pg_upgrade 시 --check 결과에서 로케일 관련 경고가 뜬다면, 새 데이터 디렉토리를 초기화할 때 로케일 설정을 명시적으로 맞춰줍니다.

이슈 2: 제거된 파라미터 (postgresql.conf)

PostgreSQL 18에서는 기존에 deprecated되었던 일부 설정 파라미터들이 완전히 제거되었습니다.

해결 방법:

• postgresql.conf에서 더 이상 지원되지 않는 옵션을 주석 처리하거나 새로운 권장 옵션으로 변경합니다.
• 업그레이드 전 pg_upgrade가 postgresql.conf를 읽을 때 에러를 낸다면 해당 파일을 수정한 뒤 다시 시도합니다.

이슈 3: pg_hba.conf 인증 방식 변경

보안 강화로 인해 이전의 인증 방식(예: trust 또는 아주 오래된 암호화 방식)이 거부될 수 있습니다.

해결 방법:

• pg_hba.conf에서 scram-sha-256 방식을 사용하도록 업데이트하고 클라이언트 연결을 다시 확인합니다.

4. 업그레이드 완료 후 작업

• 통계 정보 업데이트: 마이그레이션된 데이터에 대해 쿼리 플래너가 올바르게 작동하도록 ./analyze_new_cluster.sh를 실행합니다.
• 이전 데이터 정리: 모든 기능이 정상 작동함을 확인한 후 ./delete_old_cluster.sh를 실행하여 17 버전의 데이터를 삭제합니다.

메이저 업데이트는 번거롭지만, PostgreSQL 18의 새로운 기능(성능 개선, 쿼리 최적화 등)을 사용하기 위해 꼭 필요한 과정입니다. 비슷한 문제를 겪고 계신 분들에게 이 글이 도움이 되길 바랍니다.